called. This suggests that when setting up a growable arena a minimal
(1K) original buffer be used. The function will be called with two
parameters, the number of bytes required and a pointer to the arena
requiring the space. The number of bytes requested will always be a
multiple of MMMM____BBBBLLLLKKKKSSSSZZZZ (see _aaaa_mmmm_aaaa_llll_llll_oooo_pppp_tttt below). The function should return the
address of suitably large block of memory. This block need not be
contiguous with the original arena memory. This block could be obtained
from a number of sources, such as by allocating a new shared memory
segment (via _ssss_hhhh_mmmm_gggg_eeee_tttt(2)); by mapping in another file (via _mmmm_mmmm_aaaa_pppp(2)); or by
calling _mmmm_aaaa_llll_llll_oooo_cccc(3X) to enlarge ones data space. If the _g_r_o_w function
decides that it cannot provide any more space it should return _((((_vvvv_oooo_iiii_dddd_****_))))_----_1111.
Since the allocator package involves a two-tiered allocation strategy
(small blocks and large blocks), various anomalies (such as not being
able to allocate any space!) can arise when using very small non-
growable arenas ( _l_e_n less than 64K). For this reason _aaaa_cccc_rrrr_eeee_aaaa_tttt_eeee will set
MMMM____BBBBLLLLKKKKSSSSZZZZ to 512 and MMMM____MMMMXXXXFFFFAAAASSSSTTTT to 0 for all arenas whose size is less than
64K and is non-growable. These default values may be changed via
_aaaa_mmmm_aaaa_llll_llll_oooo_pppp_tttt. Users creating very small growable arenas may likewise have to
tune the resulting arena's parameters.
If the arena is to be shared between multiple processes, then the
MMMMEEEEMMMM____SSSSHHHHAAAARRRREEEEDDDD flag should be passed, and _u_s_h_d_r must be a pointer to a shared
arena as returned from _uuuu_ssss_iiii_nnnn_iiii_tttt(3P). Calling _aaaa_cccc_rrrr_eeee_aaaa_tttt_eeee with the MMMMEEEEMMMM____SSSSHHHHAAAARRRREEEEDDDD
flag tells _aaaa_cccc_rrrr_eeee_aaaa_tttt_eeee to allocate a lock, which it then uses to single
thread all accesses to the arena. It is the callers responsibility to
ensure that the arena is accessible by all processes, and to provide a
mechanism to exchange the addresses returned by _aaaa_mmmm_aaaa_llll_llll_oooo_cccc between the
various processes.
The _MMMM_EEEE_MMMM______NNNN_OOOO_AAAA_UUUU_TTTT_OOOO_GGGG_RRRR_OOOO_WWWW flag to _aaaa_cccc_rrrr_eeee_aaaa_tttt_eeee specifies that the memory for the
arena is not going to come from a growable _mmmm_mmmm_aaaa_pppp file. This flag only has
meaning for non-growable arenas. The default grow function (the one that
slowly doles out up to _l_e_n bytes) attempts to make sure that the memory
being returned is in fact available. For all but autogrow mapped files,
this is always the case - the memory was alloced somehow and by
definition is available to the user process. Autogrow mapped files on
the other hand can fail when first accessing a new largest page due to
the file system on which the mmaped file resides being full. In this
case, accesses to the file via a mapping result in a _SSSS_IIII_GGGG_BBBB_UUUU_SSSS signal being
sent. To avoid giving the applications (seemingly) random _SSSS_IIII_GGGG_BBBB_UUUU_SSSS
signals, the default grow function performs a system call to validate the
memory, and if it gets a failure, returns -1 (which subsequently causes
_aaaa_mmmm_aaaa_llll_llll_oooo_cccc to return NULL).
_aaaa_dddd_eeee_llll_eeee_tttt_eeee causes any resources allocated for the arena (e.g. semaphores) to
be freed. Nothing is done with the arena memory itself. No further
calls to any arena functions should be made after calling _aaaa_dddd_eeee_llll_eeee_tttt_eeee.
_aaaa_mmmm_aaaa_llll_llll_oooo_cccc returns a pointer to a block of at least _s_i_z_e bytes suitably
The argument to _aaaa_ffff_rrrr_eeee_eeee is a pointer to a block previously allocated by
_aaaa_mmmm_aaaa_llll_llll_oooo_cccc; after _aaaa_ffff_rrrr_eeee_eeee is performed this space is made available for
further allocation, and its contents are destroyed (see _aaaa_mmmm_aaaa_llll_llll_oooo_pppp_tttt below
for a way to change this behavior).
Undefined results will occur if the space assigned by _aaaa_mmmm_aaaa_llll_llll_oooo_cccc is overrun
or if some random number is handed to _aaaa_ffff_rrrr_eeee_eeee. It is always permitted to
pass NULL to _aaaa_ffff_rrrr_eeee_eeee.
_aaaa_rrrr_eeee_aaaa_llll_llll_oooo_cccc changes the size of the block pointed to by _p_t_r to _s_i_z_e bytes
and returns a pointer to the (possibly moved) block. The contents will
be unchanged up to the lesser of the new and old sizes. In the special
case of a null _p_t_r, _aaaa_rrrr_eeee_aaaa_llll_llll_oooo_cccc degenerates to _aaaa_mmmm_aaaa_llll_llll_oooo_cccc. A zero _s_i_z_e causes
the passed block to be freed.
_aaaa_cccc_aaaa_llll_llll_oooo_cccc allocates space for an array of _n_e_l_e_m elements of size _e_l_s_i_z_e.
The space is initialized to zeros.
_aaaa_rrrr_eeee_cccc_aaaa_llll_llll_oooo_cccc combines _aaaa_rrrr_eeee_aaaa_llll_llll_oooo_cccc and _aaaa_cccc_aaaa_llll_llll_oooo_cccc. If the size of the block
increases, any new bytes are initialized to zero. Note that for this to
work properly, all allocations of a given pointer must go through
_aaaa_rrrr_eeee_cccc_aaaa_llll_llll_oooo_cccc. If the original pointer was allocated with either _aaaa_mmmm_aaaa_llll_llll_oooo_cccc or
_aaaa_rrrr_eeee_aaaa_llll_llll_oooo_cccc some new bytes may not be set properly to zero.
_aaaa_mmmm_eeee_mmmm_aaaa_llll_iiii_gggg_nnnn allocates _s_i_z_e bytes on a specified alignment boundary, and
returns a pointer to the allocated block. The value of the returned
address is guaranteed to be an even multiple of _a_l_i_g_n. Note: the value
of _a_l_i_g_n must be a power of two, and must be greater than or equal to the
size of a word, or, for 64 bit objects, the size of a doubleword.
_aaaa_mmmm_aaaa_llll_llll_oooo_cccc_bbbb_llll_kkkk_ssss_iiii_zzzz_eeee returns the actual size of the block pointed to by _p_t_r.
The returned size may be greater than the original requested size due to
padding and alignment.
_aaaa_mmmm_aaaa_llll_llll_oooo_pppp_tttt provides for control over the allocation algorithm. The
available values for _c_m_d are:
_MMMM______MMMM_XXXX_FFFF_AAAA_SSSS_TTTT Set _m_a_x_f_a_s_t to _v_a_l_u_e. The algorithm allocates all blocks at or
below the size of _m_a_x_f_a_s_t in large groups and then doles them
out very quickly. The default value for _m_a_x_f_a_s_t is 28.
_MMMM______NNNN_LLLL_BBBB_LLLL_KKKK_SSSS Set _n_u_m_l_b_l_k_s to _v_a_l_u_e. The above mentioned ``large groups''
each contain _n_u_m_l_b_l_k_s blocks. _n_u_m_l_b_l_k_s must be greater than 0.
The default value for _n_u_m_l_b_l_k_s is 100.
_MMMM______GGGG_RRRR_AAAA_IIII_NNNN Set _g_r_a_i_n to _v_a_l_u_e. Requests less than or equal to _m_a_x_f_a_s_t will
have the size of a pointer added to them and be rounded up to
the next multiple of _g_r_a_i_n. _v_a_l_u_e will be rounded up to a
multiple of the alignment size (16 bytes) when _g_r_a_i_n is set.
_g_r_a_i_n must be greater than 0. The default value of _g_r_a_i_n is 16.
_MMMM______KKKK_EEEE_EEEE_PPPP Preserve data in a freed block until the next _aaaa_mmmm_aaaa_llll_llll_oooo_cccc, _aaaa_rrrr_eeee_aaaa_llll_llll_oooo_cccc,
or _aaaa_cccc_aaaa_llll_llll_oooo_cccc. This option is provided only for compatibility with
the old version of _mmmm_aaaa_llll_llll_oooo_cccc and is not recommended.
_MMMM______DDDD_EEEE_BBBB_UUUU_GGGG Turns debug checking on if _v_a_l_u_e is not equal to 0, otherwise
turns debug checking off. When debugging is on, each call to
_aaaa_mmmm_aaaa_llll_llll_oooo_cccc and _aaaa_ffff_rrrr_eeee_eeee causes the entire malloc arena to be scanned
and checked for consistency. This option may be invoked at any
time. Note that when debug checking is on, the performance of
_aaaa_mmmm_aaaa_llll_llll_oooo_cccc is reduced considerably.
_MMMM______BBBB_LLLL_KKKK_SSSS_ZZZZ When _aaaa_mmmm_aaaa_llll_llll_oooo_cccc requires additional space, it uses _ssss_bbbb_rrrr_kkkk(2) to
allocate enough memory for the current _aaaa_mmmm_aaaa_llll_llll_oooo_cccc request rounded
up to a minimum size (default is 8K). The new size is set to
_v_a_l_u_e after it has been rounded up to the current block
alignment. _v_a_l_u_e must be at least 512 bytes. If a lot of space
is to be allocated, setting the size larger can cut down on the
system overhead. This option may be invoked at any time.
_MMMM______MMMM_XXXX_CCCC_HHHH_KKKK By default, _aaaa_mmmm_aaaa_llll_llll_oooo_cccc trades off time versus space - if anywhere
in the arena there is a block of the appropriate size, _aaaa_mmmm_aaaa_llll_llll_oooo_cccc
will find and return it. If the arena has become fragmented due
to many _aaaa_mmmm_aaaa_llll_llll_oooo_ccccs and _aaaa_ffff_rrrr_eeee_eeee_ssss, it is possible that _aaaa_mmmm_aaaa_llll_llll_oooo_cccc will
have to search through many blocks to find one of the
appropriate size. If the arena is severely fragmented, the
average _aaaa_mmmm_aaaa_llll_llll_oooo_cccc time can be on the order of tens of milliseconds
(as opposed to a normal average of tens of microseconds). This
option allows the user to place a limit on the number of blocks
that _aaaa_mmmm_aaaa_llll_llll_oooo_cccc will search through before allocating a new block
of space from the system. Small values (less than 50) can cause
much more memory to be allocated. Values around 100 (the
default) cause very uniform response time, with a small space
penalty. This option may be invoked at any time.
_MMMM______FFFF_RRRR_EEEE_EEEE_HHHH_DDDD When _v_a_l_u_e is not zero, _aaaa_ffff_rrrr_eeee_eeee, _aaaa_rrrr_eeee_cccc_aaaa_llll_llll_oooo_cccc, and _aaaa_rrrr_eeee_aaaa_llll_llll_oooo_cccc will
place any freed memory in the front of the free list(s) instead
of at the end (which is the default). Some applications will
benefit in processing speed and space compaction by having freed
memory placed at the beginning of the free list(s) (a zero
_aaaa_cccc_rrrr_eeee_aaaa_tttt_eeee will return NULL and set _eeee_rrrr_rrrr_nnnn_oooo if either _l_e_n is less than 1K or
the MMMMEEEEMMMM____SSSSHHHHAAAARRRREEEEDDDD flag is passed but _u_s_h_d_r is NNNNUUUULLLLLLLL. _aaaa_mmmm_aaaa_llll_llll_oooo_cccc, _aaaa_rrrr_eeee_cccc_aaaa_llll_llll_oooo_cccc,
_aaaa_mmmm_eeee_mmmm_aaaa_llll_iiii_gggg_nnnn, _aaaa_rrrr_eeee_aaaa_llll_llll_oooo_cccc and _aaaa_cccc_aaaa_llll_llll_oooo_cccc return a NULL pointer if there is not
enough available memory. On the first call to _aaaa_mmmm_aaaa_llll_llll_oooo_cccc, _aaaa_rrrr_eeee_cccc_aaaa_llll_llll_oooo_cccc,
_aaaa_rrrr_eeee_aaaa_llll_llll_oooo_cccc, or _aaaa_cccc_aaaa_llll_llll_oooo_cccc -1 may be returned and _eeee_rrrr_rrrr_nnnn_oooo set if the MMMMEEEEMMMM____SSSSHHHHAAAARRRREEEEDDDD
flag is set and it is impossible to allocate a lock. When _aaaa_rrrr_eeee_aaaa_llll_llll_oooo_cccc or
_aaaa_rrrr_eeee_cccc_aaaa_llll_llll_oooo_cccc returns NULL, the block pointed to by _p_t_r is left intact. If
_aaaa_mmmm_aaaa_llll_llll_oooo_pppp_tttt is called after any allocation (for most _c_m_d arguments) or if
_c_m_d or _v_a_l_u_e are invalid, non-zero is returned. Otherwise, it returns
